2007-06-09 Matthias Clasen <mclasen@redhat.com>
+ * gtk/gtkwidget.c:
+ * gtk/gtkscrolledwindow.c: Update docs
+ * gtk/gtkwidget.h: Deprecate gtk_widget_{ref,unref}
+
* gtk/gtkbox.c: Move docs inline.
* gtk/gtkrange.c:
2007-06-09 Matthias Clasen <mclasen@redhat.com>
+ * gtk/tmpl/gtkbindings.sgml:
+ * gtk/tmpl/gtkrc.sgml:
+ * gtk/tmpl/gtkwidget.sgml:
+ * gtk/tmpl/gtkrecentmanager.sgml:
+ * gtk/*.sgml:
+ * gtk/tmpl/gtkstock.sgml:
+ * gtk/gtk-sections.txt: Updates
+
+ * gtk/Makefile.am: Exclude another private header
+
* gtk/tmpl/gtkbox.sgml: Move docs inline
2007-06-08 Matthias Clasen <mclasen@redhat.com>
gtkxembed.h \
gtkwin32embed.h \
gtkwin32embedwidget.h \
+ gtkwindow-decorate.h \
xdgmime \
xembed.h
of the tools are already included in the source packages. But
it's useful to know a bit about how packages that use these
tools work. A source package is distributed as a
- <literal>tar.gz</literal> file which you unpack into a
- directory full of the source files as follows:
+ <literal>tar.gz</literal> or <literal>tar.bz2</literal> file
+ which you unpack into a directory full of the source files as follows:
</para>
<programlisting>
tar xvfz gtk+-2.0.0.tar.gz
+ tar xvfj gtk+-2.0.0.tar.bz2
</programlisting>
<para>
In the toplevel of the directory that is created, there will be
needed for that library along with version number information.)
The version of <command>pkg-config</command> needed to build
GTK+ is mirrored in the <filename>dependencies</filename> directory
- on the <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.6/">GTK+ FTP
+ on the <ulink url="ftp://ftp.gtk.org/pub/gtk/">GTK+ FTP
site.</ulink>
</para>
</listitem>
<arg>--disable-xkb</arg>
<arg>--enable-xkb</arg>
</group>
+ <group>
+ <arg>--disable-xinerama</arg>
+ <arg>--enable-xinerama</arg>
+ </group>
<group>
<arg>--disable-gtk-doc</arg>
<arg>--enable-gtk-doc</arg>
<arg>--with-xinput=[no|yes]</arg>
</group>
<group>
- <arg>--with-gdktarget=[x11|linux-fb|win32]</arg>
+ <arg>--with-gdktarget=[x11|linux-fb|win32|quartz|directfb]</arg>
</group>
<group>
<arg>--disable-shadowfb</arg>
</para>
</formalpara>
+ <formalpara>
+ <title><systemitem>--disable-xinerama</systemitem> and
+ <systemitem>--enable-xinerama</systemitem></title>
+
+ <para>
+ By default the <command>configure</command> script will try
+ to link against the Xinerama libraries if they are found.
+ These options can be used to explicitly control whether
+ Xinerama should be used.
+ </para>
+ </formalpara>
+
<formalpara>
<title><systemitem>--disable-gtk-doc</systemitem> and
<systemitem>--enable-gtk-doc</systemitem></title>
<para>
Toggles between the supported backends for GDK.
The default is x11, unless the platform is Windows, in which
- case the default is win32.
+ case the default is win32. Other supported backends are
+ the quartz backend for OS X, and the DirectFB backend
+ for the Linux framebuffer.
</para>
</formalpara>
<refsect2><title>Build requirements</title>
<para>
-Beyond the usual GTK+ build requirements, the DirectFB backend (obviously) needs
-the DirectFB libraries (at least 0.9.21) and Cairo compiled with DirectFB support.
+Beyond the usual GTK+ build requirements, the DirectFB backend (obviously)
+needs the DirectFB libraries (at least 0.9.21) and cairo compiled with
+DirectFB support.
</para>
-
</refsect2>
-
-<!--
- FIXME: it seems most of the options listed in _gdk_windowing_args
- are ignored, and they need to be described by somebody who knows
- what they are supposed to do...
-
-<refsect2><title>DirectFB-specific commandline options</title>
-
-<para>
-The DirectFB GDB backend can be influenced with some additional
-command line arguments.
-</para>
-
-<formalpara>
- <title><systemitem>dfb-help</systemitem></title>
- <para>
- Display help for DirectFB-specific commandline options.
- </para>
-</formalpara>
-
-<formalpara>
- <title><systemitem>dfb=<replaceable>value</replaceable></systemitem></title>
- <para>
- Possible values: sdl, system.
- </para>
-</formalpara>
-
-<formalpara>
- <title><systemitem>disable-aa-fonts=<replaceable>number</replaceable></systemitem></title>
- <para>
- If <replaceable>number</replaceable> is 1, disable antialising for fonts.
- </para>
-</formalpara>
-
-<formalpara>
- <title><systemitem>argb-font=<replaceable>number</replaceable></systemitem></title>
- <para>
- If <replaceable>number</replaceable> is 1, enable ARGB fonts.
- </para>
-</formalpara>
-
-<formalpara>
- <title><systemitem>transparent-unfocused=<replaceable>number</replaceable></systemitem></title>
- <para>
- If <replaceable>number</replaceable> is 1, make unfocused windows transparent.
- </para>
-</formalpara>
-
-<formalpara>
- <title><systemitem>glyph-surface-cache=<replaceable>number</replaceable></systemitem></title>
- <para>
- Set the size of the glyph surface cache. The default value is 8.
- </para>
-</formalpara>
-
-<formalpara>
- <title><systemitem>enable-color-keyring=<replaceable>number</replaceable></systemitem></title>
- <para>
- If <replaceable>number</replaceable> is 1, turn on the color keyring.
- </para>
-</formalpara>
-
--->
-
</refsect1>
-
</refentry>
<varlistentry>
<term>Pango</term>
<listitem><para>
-
Pango is a library for internationalized text handling. It centers
-around the <link linkend="PangoLayout">PangoLayout</link> object, representing
-a paragraph of text.
-Pango provides the engine for <link linkend="GtkTextView">GtkTextView</link>,
-<link linkend="GtkLabel">GtkLabel</link>,
-<link linkend="GtkEntry">GtkEntry</link>, and
+around the #PangoLayout object, representing a paragraph of text.
+Pango provides the engine for #GtkTextView, #GtkLabel, #GtkEntry, and
other widgets that display text.
-
</para></listitem>
</varlistentry>
<varlistentry>
<term>ATK</term>
<listitem><para>
-
ATK is the Accessibility Toolkit. It provides a set of generic
interfaces allowing accessibility technologies to interact with a
graphical user interface. For example, a screen reader uses ATK to
discover the text in an interface and read it to blind users. GTK+
widgets have built-in support for accessibility using the ATK
framework.
-
</para></listitem>
</varlistentry>
<varlistentry>
<term>GdkPixbuf</term>
<listitem><para>
-This is a small library which allows you to create <link linkend="GdkPixbuf">GdkPixbuf</link>
+This is a small library which allows you to create #GdkPixbuf
("pixel buffer") objects from image data or image files.
-Use a <link linkend="GdkPixbuf">GdkPixbuf</link> in combination with <link linkend="GtkImage">GtkImage</link> to display images.
+Use a #GdkPixbuf in combination with #GtkImage to display images.
</para></listitem>
</varlistentry>
<varlistentry>
<term>GTK+</term>
<listitem><para>
-
The GTK+ library itself contains <firstterm>widgets</firstterm>,
-that is, GUI components such as <link linkend="GtkButton">GtkButton</link> or
-<link linkend="GtkTextView">GtkTextView</link>.
-
+that is, GUI components such as #GtkButton or #GtkTextView.
</para></listitem>
</varlistentry>
</variablelist>
gtk_tree_store_set_value
gtk_tree_store_set
gtk_tree_store_set_valist
+gtk_tree_store_set_valuesv
gtk_tree_store_remove
gtk_tree_store_insert
gtk_tree_store_insert_before
gtk_tree_view_column_cell_is_visible
gtk_tree_view_column_focus_cell
gtk_tree_view_column_queue_resize
+gtk_tree_view_column_get_tree_view
<SUBSECTION Standard>
GTK_TREE_VIEW_COLUMN
GTK_IS_TREE_VIEW_COLUMN
gtk_list_store_set
gtk_list_store_set_valist
gtk_list_store_set_value
+gtk_list_store_set_valuesv
gtk_list_store_remove
gtk_list_store_insert
gtk_list_store_insert_before
gtk_widget_modify_text
gtk_widget_modify_base
gtk_widget_modify_font
+gtk_widget_modify_cursor
gtk_widget_create_pango_context
gtk_widget_get_pango_context
gtk_widget_create_pango_layout
GTK_STOCK_DIALOG_QUESTION
GTK_STOCK_DIALOG_WARNING
GTK_STOCK_DIRECTORY
+GTK_STOCK_DISCARD
GTK_STOCK_DISCONNECT
GTK_STOCK_DND
GTK_STOCK_DND_MULTIPLE
g_object_unref (pixbuf);
</programlisting></informalexample>
If the g_object_new() construction scares you, you can also use
- gtk_about_dialog_new() to construct the dialog and then use the setters for
- the individual properties.
+ gtk_about_dialog_new() to construct the dialog and then use the
+ setters for the individual properties.
</para>
<para>
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Second Item");
gtk_combo_box_append_text (GTK_COMBO_BOX (combo_box), "Third Item");
</programlisting></informalexample>
- In order to react to the user's selection, connect to the "changed"
- signal on the combo box and use gtk_combo_box_get_active()
+ In order to react to the user's selection, connect to the
+ #GtkComboBox::changed signal and use gtk_combo_box_get_active()
to retrieve the index of the selected item.
</para>
<para>
Porting an application from <structname>GnomeHRef</structname> to
#GtkLinkButton is very simple. #GtkLinkButton does not have a
- default action for "clicked" signal. So instead of simply creating
- the widget
+ default action for #GtkButton::clicked signal. So instead of simply
+ creating the widget
<informalexample><programlisting>
GtkWidget *button;
button = gnome_href_new (url, "");
</programlisting></informalexample>
you will have to handle the activation of the #GtkLinkButton, using
- the "clicked" signal for instance
+ the ::clicked signal for instance
<informalexample><programlisting>
static void
link_button_clicked_cb (GtkWidget *widget,
</formalpara>
<para>
- The #GtkWidget::popup_menu signal instructs the widget for which
+ The #GtkWidget::popup-menu signal instructs the widget for which
it is emitted to create a context-sensitive popup menu. By default,
the <link linkend="gtk-bindings">key binding mechanism</link> is set to
emit this signal when the
<listitem>
<para>
- In your ::button-press handler, call this function
+ In your #GtkWidget::button-press-event handler, call this function
when you need to pop up a menu:
</para>
<listitem>
<para>
- Implement a handler for the ::popup-menu signal:
+ Implement a handler for the #GtkWidget::popup-menu signal:
</para>
<programlisting>
provide your own <link
linkend="GtkMenuPositionFunc">menu-positioning function</link>
in the case where the <parameter>event</parameter> is
- <constant>NULL</constant>. This function should compute the
- desired position for a menu when it is invoked through the
- keyboard. For example, #GtkEntry aligns the
- top edge of its popup menu with the bottom edge of the entry.
+ %NULL. This function should compute the desired position for
+ a menu when it is invoked through the keyboard. For example,
+ #GtkEntry aligns the top edge of its popup menu with the bottom
+ edge of the entry.
</para>
</note>
able to take the keyboard focus. In general, widgets should
be fully usable through the keyboard and not just the mouse.
The very first step of this is to ensure that your widget
- turns on the %GTK_CAN_FOCUS <link
- linkend="gtkwidgetflags">flag</link>.
+ turns on the %GTK_CAN_FOCUS <link linkend="gtkwidgetflags">flag</link>.
</para>
</note>
</section>
<para>
Regions have an internal representation that is accessible as a
- list of rectangles. To turn the
+ list of rectangles. To turn the
<structfield>GdkEventExpose.region</structfield> field into such
a list, use gdk_region_get_rectangles():
</para>
<formalpara>
<title>Why</title>
<para>
- With
- gtk_accelerator_get_default_mod_mask()
- you can test for modifier keys reliably; this way your key
- event handlers will work correctly even if
- <keycap>NumLock</keycap> or <keycap>CapsLock</keycap> are
- activated.
+ With gtk_accelerator_get_default_mod_mask() you can test for
+ modifier keys reliably; this way your key event handlers will
+ work correctly even if <keycap>NumLock</keycap> or
+ <keycap>CapsLock</keycap> are activated.
</para>
</formalpara>
indicates the modifier state at the time the key was pressed.
Modifiers are keys like <keycap>Control</keycap> and
<keycap>NumLock</keycap>. When implementing a
- #GtkWidget::key_press_event handler, you should use
+ #GtkWidget::key-press-event handler, you should use
gtk_accelerator_get_default_mod_mask() to
test against modifier keys. This function returns a bit mask
which encompasses all the modifiers which the user may be
gtk_window_set_icon_name()) and images (see gtk_image_set_icon_name()).
In GTK+ 2.8, you can also use named icons for drag-and-drop (see
gtk_drag_source_set_icon_name()) and in treeview cells (see the
- #GtkCellRendererPixbuf:icon_name property).
+ #GtkCellRendererPixbuf:icon-name property).
</para>
</section>
</chapter>
<qandaentry>
-<question><para>How do I port from one GTK+
+<question><para>How do I port from one GTK+
version to another?</para></question>
<answer>
<answer>
<para>
-See the documentation for #GObject and #GtkObject. For #GObject note specifically
-g_object_ref() and g_object_unref(). #GtkObject is a subclass of #GObject so the
-same points apply, except that it has a "floating" state (explained in its
-documentation).
+See the documentation for #GObject and #GtkObject. For #GObject note
+specifically g_object_ref() and g_object_unref(). #GtkObject is a subclass
+of #GObject so the same points apply, except that it has a "floating" state
+(explained in its documentation).
</para>
<para>
For strings returned from functions, they will be declared "const" (using
-#G_CONST_RETURN) if they should not be freed. Non-const strings should be freed
-with g_free(). Arrays follow the same rule. (If you find an exception to the rules,
-please report a bug to <ulink
+#G_CONST_RETURN) if they should not be freed. Non-const strings should be
+freed with g_free(). Arrays follow the same rule. (If you find an exception
+
to the rules, please report a bug to <ulink
url="http://bugzilla.gnome.org">http://bugzilla.gnome.org</ulink>.)
</para>
</para>
<para>
-To to get this, you must acquire a reference to the widget and drop the floating
-reference (<quote>ref and sink</quote> in GTK+ parlance) after creating it:
+To to get this, you must acquire a reference to the widget and drop the
+floating reference (<quote>ref and sink</quote> in GTK+ parlance) after
+creating it:
<informalexample><programlisting>
foo = gtk_foo_new (<!-- -->);
g_object_ref (foo);
<answer>
<para>
-This is covered in the
-<link linkend="gdk-Threads">GDK threads documentation</link>.
-See also the <link linkend="glib-Threads">GThread</link> documentation for portable
-threading primitives.
+This is covered in the <link linkend="gdk-Threads">GDK threads
+documentation</link>. See also the <link linkend="glib-Threads">GThread</link>
+documentation for portable threading primitives.
</para>
</answer>
<para>
Most people use <ulink url="http://www.gnu.org/software/gettext/">GNU
gettext</ulink>, already required in order to install GLib. On a UNIX
-or Linux system with gettext installed, type <literal>info
-gettext</literal> to read the documentation.
+or Linux system with gettext installed, type <literal>info gettext</literal>
+to read the documentation.
</para>
<para>
The short checklist on how to use gettext is: call bindtextdomain() so gettext
#define N_(x) x
</programlisting>
</informalexample>
-You use N_() (N stands for no-op) to mark a string for translation in a context
-where a function call to gettext() is not allowed, such as in an array initializer.
+You use N_() (N stands for no-op) to mark a string for translation in a
+context where a function call to gettext() is not allowed, such as in an
+array initializer.
You eventually have to call gettext() on the string to actually fetch the
-translation. _() both marks the string for translation and actually translates it.
+translation. _() both marks the string for translation and actually
+translates it.
</para>
<para>
Nowadays, GLib provides the common shorthand macros in the header file
-<filename>gi18n.h</filename>, so you don't have to define them yourself, just
-include that header.
+<filename>gi18n.h</filename>, so you don't have to define them yourself,
+just include that header.
</para>
<para>
Code using these macros ends up looking like this:
</informalexample>
</para>
<para>
-Libraries using gettext should use dgettext() instead of gettext(), which allows
-them to specify the translation domain each time they ask for a translation. Libraries
-should also avoid calling textdomain(), since they'll be specifying the domain instead
-of using the default.For dgettext() the _() macro can be defined as:
+Libraries using gettext should use dgettext() instead of gettext(), which
+allows them to specify the translation domain each time they ask for a
+translation. Libraries should also avoid calling textdomain(), since they
+will be specifying the domain instead of using the default. For dgettext()
+the _() macro can be defined as:
<informalexample>
<programlisting>
#define _(x) dgettext ("MyDomain", x)
</informalexample>
</para>
<para>
-Again, GLib comes with the <filename>gi18n-lib.h</filename>, saving you the trouble
-of defining the macros by hand. The macros in that header expect the translation
-domain to be specified by the %GETTEXT_PACKAGE macro.
+Again, GLib comes with the <filename>gi18n-lib.h</filename>, saving you the
+trouble of defining the macros by hand. The macros in that header expect the
+translation domain to be specified by the %GETTEXT_PACKAGE macro.
</para>
</answer>
</qandaentry>
<answer>
<para>
GTK+ uses <ulink url="http://www.unicode.org">Unicode</ulink> (more exactly
-UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a
- sequence of one to six bytes and has a number of nice
- properties which make it a good choice for working with Unicode
- text in C programs:
+UTF-8) for all text. UTF-8 encodes each Unicode codepoint as a sequence of
+one to six bytes and has a number of nice properties which make it a good
+choice for working with Unicode text in C programs:
<itemizedlist>
<listitem><para>
ASCII characters are encoded by their familiar ASCII codepoints.
ASCII characters never appear as part of any other character.
</para></listitem>
<listitem><para>
-The zero byte doesn't occur as part of a character, so that UTF-8 strings can
- be manipulated with the usual C library functions for
- handling zero-terminated strings.
+The zero byte doesn't occur as part of a character, so that UTF-8 strings
+can be manipulated with the usual C library functions for handling
+zero-terminated strings.
</para></listitem>
</itemizedlist>
More information about Unicode and UTF-8 can be found in the
-<ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode FAQ for Unix/Linux</ulink>.
+<ulink url="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode i
+FAQ for Unix/Linux</ulink>.
GLib provides functions for converting strings between UTF-8 and other
- encodings, see g_locale_to_utf8() and g_convert().
+encodings, see g_locale_to_utf8() and g_convert().
</para>
<para>
Text coming from external sources (e.g. files or user input), has to be
- converted to UTF-8 before being handed over to GTK+. The
- following example writes the content of a IS0-8859-1 encoded text
- file to <literal>stdout</literal>:
+converted to UTF-8 before being handed over to GTK+. The following example
+writes the content of a IS0-8859-1 encoded text file to
+<literal>stdout</literal>:
<informalexample><programlisting>
gchar *text, *utf8_text;
gsize length;
</para>
<para>
For string literals in the source code, there are several alternatives for
- handling non-ASCII content:
+handling non-ASCII content:
<variablelist>
<varlistentry><term>direct UTF-8</term>
<listitem><para>
<listitem><para>
If the string literals can be represented in an encoding which your toolchain
can handle (e.g. IS0-8859-1), you can write your source files in that encoding
-and use g_convert() to convert the strings to UTF-8 at runtime. Note that this has
-some runtime overhead, so you may want to move the conversion out of inner loops.
+and use g_convert() to convert the strings to UTF-8 at runtime. Note that this
+has some runtime overhead, so you may want to move the conversion out of inner
+loops.
</para></listitem>
</varlistentry>
</variablelist>
of C that's also valid C++, so you can simply use the normal GTK+ API
in a C++ program. Alternatively, you can use a "C++ binding"
such as <ulink url="http://gtkmm.sourceforge.net/">gtkmm</ulink>
-which provides a C++-native API.
+which provides a native C++ API.
</para>
<para>
When using GTK+ directly, keep in mind that only functions can be
<para>
See the <ulink url="http://www.gtk.org/bindings.html">list of language
bindings</ulink> on <ulink
- url="http://www.gtk.org">http://www.gtk.org</ulink>.
+url="http://www.gtk.org">http://www.gtk.org</ulink>.
</para>
</answer>
<answer>
<para>
-To load an image file straight into a display widget, use gtk_image_new_from_file()
-<footnote><para> If the file load fails, gtk_image_new_from_file() will display no
-image graphic — to detect a failed load yourself, use gdk_pixbuf_new_from_file()
-directly, then gtk_image_new_from_pixbuf().</para></footnote>.
-To load an image for another purpose, use gdk_pixbuf_new_from_file(). To load an
-animation, use gdk_pixbuf_animation_new_from_file().
-gdk_pixbuf_animation_new_from_file() can also load non-animated images, so use it
-in combination with gdk_pixbuf_animation_is_static_image() to load a file of unknown
-type.
+To load an image file straight into a display widget, use
+gtk_image_new_from_file() <footnote><para> If the file load fails,
+gtk_image_new_from_file() will display no image graphic — to detect
+a failed load yourself, use gdk_pixbuf_new_from_file() directly, then
+gtk_image_new_from_pixbuf().</para></footnote>.
+To load an image for another purpose, use gdk_pixbuf_new_from_file(). To i
+load an animation, use gdk_pixbuf_animation_new_from_file().
+gdk_pixbuf_animation_new_from_file() can also load non-animated images, so
+use it in combination with gdk_pixbuf_animation_is_static_image() to load a
+file of unknown type.
</para>
<para>
To load an image or animation file asynchronously (without blocking), use
<qandaentry>
<question>
<para>
-Why are types not registered if I use their <literal>GTK_TYPE_BLAH</literal> macro ?
+Why are types not registered if I use their <literal>GTK_TYPE_BLAH</literal>
+macro ?
</para>
</question>
<answer>
<para>
The <literal>GTK_TYPE_BLAH</literal> macros are defined as calls to
-<literal>gtk_blah_get_type()</literal>, and the <literal>_get_type()</literal> functions
-are declared as <literal>G_GNUC_CONST</literal> which allows the compiler to optimize
+<literal>gtk_blah_get_type()</literal>, and the <literal>_get_type()</literal> i
+functions are declared as %G_GNUC_CONST which allows the compiler to optimize
the call away if it appears that the value is not being used.
</para>
<para>
-A common workaround for this problem is to store the result in a volatile variable,
-which keeps the compiler from optimizing the call away.
+A common workaround for this problem is to store the result in a volatile
+variable, which keeps the compiler from optimizing the call away.
<informalexample><programlisting>
volatile GType dummy = GTK_TYPE_BLAH;
</programlisting></informalexample>
in newly-written code, it has a number of problems that are best avoided.
</para>
<para>
-If you only have a small amount of text, #GtkLabel may also be appropriate of course.
-It can be made selectable with gtk_label_set_selectable(). For a single-line text
-entry, see #GtkEntry.
+If you only have a small amount of text, #GtkLabel may also be appropriate
+of course. It can be made selectable with gtk_label_set_selectable(). For a
+single-line text entry, see #GtkEntry.
</para>
</answer>
</qandaentry>
<answer>
<para>
-#GtkImage can display images in just about any format GTK+ understands. You can also
-use #GtkDrawingArea if you need to do something more complex, such as draw text or
-graphics over the top of the image.
+#GtkImage can display images in just about any format GTK+ understands.
+You can also use #GtkDrawingArea if you need to do something more complex,
+such as draw text or graphics over the top of the image.
</para>
</answer>
</qandaentry>
<answer><para>
See gtk_widget_modify_fg(), gtk_widget_modify_bg(), gtk_widget_modify_base(),
and gtk_widget_modify_text(). See <link linkend="gtk-Resource-Files">GTK+
-resource files</link> for more discussion. You can also change widget color by
-installing a resource file and parsing it with gtk_rc_add_default_file().
+resource files</link> for more discussion. You can also change widget color
+by installing a resource file and parsing it with gtk_rc_add_default_file().
The advantage of a resource file is that users can then override the
color you've chosen.
</para>
-<para>To change the background color for widgets such as #GtkLabel that have no
-background, place them in a #GtkEventBox and set the background of the event box.
+<para>To change the background color for widgets such as #GtkLabel that have
+no background, place them in a #GtkEventBox and set the background of the
+event box.
</para></answer>
</qandaentry>
</para></question>
<answer><para>
-This has several possible answers, depending on what exactly you want to achieve.
-One option is gtk_widget_modify_font(). Note that this function can be used to
-change only the font size, as in the following example:
+This has several possible answers, depending on what exactly you want to
+achieve. One option is gtk_widget_modify_font(). Note that this function
+can be used to change only the font size, as in the following example:
<programlisting>
PangoFontDesc *font_desc = pango_font_description_new (<!-- -->);
pango_font_description_set_size (font_desc, 40);
</programlisting>
</para>
<para>
-If you want to make the text of a label larger, you can use gtk_label_set_markup():
+If you want to make the text of a label larger, you can use
+gtk_label_set_markup():
<programlisting>
gtk_label_set_markup (label, "<big>big text</big>");
</programlisting>
This is preferred for many apps because it's a relative size to the
-user's chosen font size. See g_markup_escape_text() if you are constructing such
-strings on the fly.
+user's chosen font size. See g_markup_escape_text() if you are
+constructing such strings on the fly.
</para>
<para>
You can also change the font of a widget by putting
<programlisting>
gtk-font-name = "Sans 30"
</programlisting>
-in a resource file and parsing it with gtk_rc_add_default_file(). The advantage of
-a resource file is that users can then override the font you've chosen. See
-<link linkend="gtk-Resource-Files">GTK+ resource files</link> for more
-discussion.
+in a resource file and parsing it with gtk_rc_add_default_file().
+The advantage of a resource file is that users can then override the font you
+have chosen. See <link linkend="gtk-Resource-Files">GTK+ resource files</link>
+for more discussion.
</para>
</answer>
</qandaentry>
</para></question>
<answer><para>
-If you use gtk_text_buffer_insert_with_tags() with appropriate tags to select the
-font, the inserted text will have the desired appearance, but text typed in by the
-user before or after the tagged block will appear in the default style.
+If you use gtk_text_buffer_insert_with_tags() with appropriate tags to select
+the font, the inserted text will have the desired appearance, but text typed
+in by the user before or after the tagged block will appear in the default
+style.
</para>
<para>
To ensure that all text has the desired appearance, use gtk_widget_modify_font()
<answer>
<para>
Remember that the #GtkTreeModel columns don't necessarily have to be displayed.
-So you can put non-user-visible data in your model just like any other data, and
-retrieve it with gtk_tree_model_get(). See the
+So you can put non-user-visible data in your model just like any other data,
+and retrieve it with gtk_tree_model_get(). See the
<link linkend="TreeWidget">tree widget overview</link>.
</para>
</answer>
<answer>
<para>
-You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn using
-gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end(). So pack both
-a #GtkCellRendererPixbuf and a #GtkCellRendererText into the column.
+You can pack more than one #GtkCellRenderer into a single #GtkTreeViewColumn
+using gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end().
+So pack both a #GtkCellRendererPixbuf and a #GtkCellRendererText into the
+column.
</para>
</answer>
</qandaentry>
<answer>
<para>
Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel
-interface. Consequentially, the can use any function this interface implements.
-The easiest way to read a set of data back is to use gtk_tree_model_get().
+interface. Consequentially, the can use any function this interface
+implements. The easiest way to read a set of data back is to use
+gtk_tree_model_get().
</para>
</answer>
</qandaentry>
</para></question>
<answer><para>
Use gtk_tree_view_insert_column_with_data_func()
-or gtk_tree_view_column_set_cell_data_func() and do the conversion from number to
-string yourself (with, say, g_strdup_printf()).
+or gtk_tree_view_column_set_cell_data_func() and do the conversion from i
+number to string yourself (with, say, g_strdup_printf()).
</para>
<para>
<para>
All GTK+ applications support a number of standard commandline
-options. These are removed from <literal>argv</literal> by <link
-linkend="gtk-init">gtk_init()</link>. Modules may parse and remove
-further options. The <link linkend="x11-cmdline">X11</link> and
+options. These are removed from <literal>argv</literal> by gtk_init().
+Modules may parse and remove further options. The
+<link linkend="x11-cmdline">X11</link> and
<link linkend="win32-cmdline">Windows</link> GDK backends parse
some additional commandline options.
</para>
<title><systemitem>--class <replaceable>class</replaceable></systemitem></title>
<para>
-Sets the program class; see <link linkend="gdk-set-program-class"><function>gdk_set_program_class</function>()</link>.
+Sets the program class; see gdk_set_program_class().
</para>
</formalpara>
<para>
A list of <link linkend="GDK-Debug-Options">debug options</link>
-to turn on in addition to those
-specified in the <envar>GDK_DEBUG</envar> environment variable.
-This option is only available if GTK+ has been configured with
-<option>--enable-debug=yes</option>.
+to turn on in addition to those specified in the <envar>GDK_DEBUG</envar>
+environment variable. This option is only available if GTK+ has been
+configured with <option>--enable-debug=yes</option>.
</para>
</formalpara>
<para>
A list of <link linkend="GDK-Debug-Options">debug options</link>
-to turn off.
-This option is only available if GTK+ has been configured with
+to turn off. This option is only available if GTK+ has been configured with
<option>--enable-debug=yes</option>.
</para>
</formalpara>
</varlistentry>
</variablelist>
- The special value <literal>all</literal> can be used to turn on all debug options.
+ The special value <literal>all</literal> can be used to turn on all
+ debug options.
</para>
</formalpara>
<para>
Specifies a list of directories to search when GTK+ is looking for
dynamically loaded objects such as the modules specified by
- <envar>GTK_MODULES</envar>, theme engines, and input method
- modules. If the path to the dynamically loaded object is given
- as an absolute path name, then GTK+ loads it directly. Otherwise,
- GTK+ goes in turn through the directories in GTK_PATH, followed
- by the directory <filename>.gtk-2.0</filename> in the user's home
- directory, followed by the system default directory,
+ <envar>GTK_MODULES</envar>, theme engines, input method
+ modules, file system backends and print backends. If the path to
+ the dynamically loaded object is given as an absolute path name,
+ then GTK+ loads it directly.
+ Otherwise, GTK+ goes in turn through the directories in GTK_PATH,
+ followed by the directory <filename>.gtk-2.0</filename> in the user's
+ home directory, followed by the system default directory,
which is <filename><replaceable>libdir</replaceable>/gtk-2.0/modules</filename>.
(If <envar>GTK_EXE_PREFIX</envar> is defined, <replaceable>libdir</replaceable> is
<filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
--variable=gtk_host gtk+-2.0</literal> to determine this from a
script), and <replaceable>type</replaceable> is a directory
specific to the type of modules; currently it can be
- <literal>modules</literal>, <literal>engines</literal> or
- <literal>immodules</literal> corresponding to the three types of
- modules above. Either <replaceable>version</replaceable>,
+ <literal>modules</literal>, <literal>engines</literal>,
+ <literal>immodules</literal>, <literal>filesystems</literal> or
+ <literal>printbackends</literal>, corresponding to the types of
+ modules mentioned above. Either <replaceable>version</replaceable>,
<replaceable>host</replaceable>, or both may be omitted. GTK+ looks
first in the most specific directory, then in directories with
fewer components.
<listitem><para>Information about XIM support</para></listitem>
</varlistentry>
</variablelist>
- The special value <literal>all</literal> can be used to turn on all debug options.
+ The special value <literal>all</literal> can be used to turn on all
+ debug options.
</para>
</formalpara>
concept is more general than that; tags don't have to affect appearance. They
can instead affect the behavior of mouse and key presses, "lock" a range of
text so the user can't edit it, or countless other things. A tag is
-represented by a #GtkTextTag object. One #GtkTextTag can be applied to any number
-of text ranges in any number of buffers.
+represented by a #GtkTextTag object. One #GtkTextTag can be applied to any
+number of text ranges in any number of buffers.
</para>
<para>
<para>
Most text manipulation is accomplished with <firstterm>iterators</firstterm>,
represented by a #GtkTextIter. An iterator represents a position between two
-characters in the text buffer. #GtkTextIter is a struct designed to be allocated
-on the stack; it's guaranteed to be copiable by value and never contain any
-heap-allocated data. Iterators are not valid indefinitely; whenever the buffer
-is modified in a way that affects the number of characters in the buffer, all
-outstanding iterators become invalid. (Note that deleting 5 characters and then
-reinserting 5 still invalidates iterators, though you end up with the same
-number of characters you pass through a state with a different number).
+characters in the text buffer. #GtkTextIter is a struct designed to be
+allocated on the stack; it's guaranteed to be copiable by value and never
+contain any heap-allocated data. Iterators are not valid indefinitely;
+whenever the buffer is modified in a way that affects the number of characters
+in the buffer, all outstanding iterators become invalid. (Note that deleting
+5 characters and then reinserting 5 still invalidates iterators, though you
+end up with the same number of characters you pass through a state with a
+different number).
</para>
<para>
Because of this, iterators can't be used to preserve positions across buffer
-modifications. To preserve a position, the #GtkTextMark object is ideal. You can
-think of a mark as an invisible cursor or insertion point; it floats in the buffer,
-saving a position. If the text surrounding the mark is deleted, the mark remains
-in the position the text once occupied; if text is inserted at the mark, the
-mark ends up either to the left or to the right of the new text, depending on
-its <firstterm>gravity</firstterm>. The standard text cursor in left-to-right
-languages is a mark with right gravity, because it stays to the right of
-inserted text.
+modifications. To preserve a position, the #GtkTextMark object is ideal. You
+can think of a mark as an invisible cursor or insertion point; it floats in
+the buffer, saving a position. If the text surrounding the mark is deleted,
+the mark remains in the position the text once occupied; if text is inserted
+at the mark, the mark ends up either to the left or to the right of the new
+text, depending on its <firstterm>gravity</firstterm>. The standard text
+cursor in left-to-right languages is a mark with right gravity, because it
+stays to the right of inserted text.
</para>
<para>
Like tags, marks can be either named or anonymous. There are two marks built-in
to #GtkTextBuffer; these are named <literal>"insert"</literal> and
<literal>"selection_bound"</literal> and refer to the insertion point and the
-boundary of the selection which is not the insertion point, respectively. If no
-text is selected, these two marks will be in the same position. You can manipulate
-what is selected and where the cursor appears by moving these marks around.
-
+boundary of the selection which is not the insertion point, respectively. If
+no text is selected, these two marks will be in the same position. You can
+manipulate what is selected and where the cursor appears by moving these
+marks around.
<footnote>
<para>
If you want to place the cursor in response to a user action, be sure to use
<!-- ##### FUNCTION gtk_bindings_activate_event ##### -->
<para>
-<!-- documented inline -->
+
</para>
@object:
reference to the start (top/left) or end (bottom/right) of the GtkBox.
@is_secondary:
-
<!-- ##### FUNCTION gtk_box_pack_start ##### -->
<para>
</para>
@box:
-@child:
-@expand:
-@box
-@fill:
+@child:
+@expand:
+@box
+@fill:
@padding:
</para>
@box:
-@widget:
+@widget:
<!-- ##### FUNCTION gtk_box_get_homogeneous ##### -->
</para>
@box:
-@child:
-@position:
+@child:
+@position:
<!-- ##### FUNCTION gtk_box_query_child_packing ##### -->
</para>
-@box:
-@child:
-@expand:
+@box:
+@child:
+@expand:
@fill:
-@padding:
+@padding:
@pack_type:
@box:
@child:
-@expand:
+@expand:
@fill:
-@padding:
-@pack_type:
+@padding:
+@pack_type:
+
+
<!-- ##### FUNCTION gtk_rc_parse_color ##### -->
<para>
-Parses a color in the <link linkend="color-format">format</link> expected in a RC file.
+
</para>
-@scanner: a #GtkScanner
-@color: a pointer to a #GtkColor structure in which to store the result
-@Returns: %G_TOKEN_NONE if parsing succeeded, otherwise the token
-that was expected but not found.
+@scanner:
+@color:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_rc_parse_color_full ##### -->
+<para>
+
+</para>
+
+@scanner:
+@style:
+@color:
+@Returns:
<!-- ##### FUNCTION gtk_rc_parse_state ##### -->
<!-- ##### STRUCT GtkRecentData ##### -->
<para>
-Meta-data passed to gtk_recent_manager_add_full(). You should
-use #GtkRecentData if you want to control the meta-data associated
-to an entry of the recently used files list when you are adding
-a new file to it.
-</para>
-
-@display_name: the string to be used when displaying the file
- inside a #GtkRecentChooser
-@description: a user readable description of the file
-@mime_type: the mime type of the file
-@app_name: the name of the application that is registering
- the file
-@app_exec: the command line that should be used when launching
- the file
-@groups: the list of group names to which the file belongs to
-@is_private: whether the file should be displayed only by
- the applications that have registered it
+
+</para>
+
+@display_name:
+@description:
+@mime_type:
+@app_name:
+@app_exec:
+@groups:
+@is_private:
+
<!-- ##### MACRO GTK_RECENT_MANAGER_ERROR ##### -->
<para>
@Since: 2.6
+<!-- ##### MACRO GTK_STOCK_DISCARD ##### -->
+<para>
+The "Discard" item.
+</para>
+
+@Since: 2.12
+
+
<!-- ##### MACRO GTK_STOCK_DISCONNECT ##### -->
<para>
The "Disconnect" icon.
<!-- ##### SIGNAL GtkWidget::hierarchy-changed ##### -->
<para>
-Emitted when there is a change in the hierarchy to
-which a widget belongs. More precisely, a widget is
-<firstterm>anchored</firstterm> when its toplevel
-ancestor is a #GtkWindow. This signal is emitted when
-a widget changes from un-anchored to anchored or vice-versa.
+
</para>
-@widget: the object which received the signal.
-@widget2: the toplevel ancestor, or %NULL
+@widget:
+@widget2:
<!-- ##### SIGNAL GtkWidget::key-press-event ##### -->
<para>
@font_desc:
+<!-- ##### FUNCTION gtk_widget_modify_cursor ##### -->
+<para>
+
+</para>
+
+@widget:
+@primary:
+@secondary:
+
+
<!-- ##### FUNCTION gtk_widget_create_pango_context ##### -->
<para>
<para>
Most applications will need to not only deal with displaying data, but
also receiving input events from users. To do this, simply get a
- reference to a selection object and connect to the "changed" signal.
+ reference to a selection object and connect to the
+ #GtkTreeSelection::changed signal.
</para>
<informalexample><programlisting><![CDATA[
/* Prototype for selection handler callback */
* @fill: pointer to return location for #GtkBox:fill child property
* @padding: pointer to return location for #GtkBox:padding child property
* @pack_type: pointer to return location for #GtkBox:pack-type child property
- *
- * Returns information about how @child is packed into @box.
+ *
+ * Obtains information about how @child is packed into @box.
*/
void
gtk_box_query_child_packing (GtkBox *box,
/**
* gtk_scrolled_window_set_placement:
* @scrolled_window: a #GtkScrolledWindow
+ * @window_placement: position of the child window
*
* Sets the placement of the contents with respect to the scrollbars
* for the scrolled window.
+ * The default is %GTK_CORNER_TOP_LEFT, meaning the child is
+ * in the top left, with the scrollbars underneath and to the right.
+ * Other values in #GtkCornerType are %GTK_CORNER_TOP_RIGHT,
+ * %GTK_CORNER_BOTTOM_LEFT, and %GTK_CORNER_BOTTOM_RIGHT.
*
* See also gtk_scrolled_window_get_placement() and
* gtk_scrolled_window_unset_placement().
* if the widget was previously unanchored
*
* The ::hierarchy-changed signal is emitted when the
- * anchored state of a widget changes. A widget is anchored,
- * if it has an ancestor that is a toplevel window.
+ * anchored state of a widget changes. A widget is
+ * <firstterm>anchored</firstterm> when its toplevel
+ * ancestor is a #GtkWindow. This signal is emitted when
+ * a widget changes from un-anchored to anchored or vice-versa.
*/
widget_signals[HIERARCHY_CHANGED] =
g_signal_new (I_("hierarchy_changed"),
*
* Return value: the widget that was referenced
*
- * Deprecated: Use g_object_ref() instead.
+ * Deprecated:2.12: Use g_object_ref() instead.
**/
GtkWidget*
gtk_widget_ref (GtkWidget *widget)
*
* Inverse of gtk_widget_ref(). Equivalent to g_object_unref().
*
- * Deprecated: Use g_object_unref() instead.
+ * Deprecated:2.12: Use g_object_unref() instead.
**/
void
gtk_widget_unref (GtkWidget *widget)
GtkWidget* gtk_widget_new (GType type,
const gchar *first_property_name,
...);
-GtkWidget* gtk_widget_ref (GtkWidget *widget);
-void gtk_widget_unref (GtkWidget *widget);
void gtk_widget_destroy (GtkWidget *widget);
void gtk_widget_destroyed (GtkWidget *widget,
GtkWidget **widget_pointer);
#ifndef GTK_DISABLE_DEPRECATED
+GtkWidget* gtk_widget_ref (GtkWidget *widget);
+void gtk_widget_unref (GtkWidget *widget);
void gtk_widget_set (GtkWidget *widget,
const gchar *first_property_name,
...) G_GNUC_NULL_TERMINATED;
projects / gtk4.git / commitdiff